home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / etc / RCS / getpwent.man,v < prev    next >
Text File  |  1990-11-27  |  7KB  |  330 lines
  1. head     1.2;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    ; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.2
  10. date     90.07.08.16.01.43;  author shirriff;  state Exp;
  11. branches ;
  12. next     1.1;
  13.  
  14. 1.1
  15. date     90.06.22.17.32.33;  author shirriff;  state Exp;
  16. branches ;
  17. next     ;
  18.  
  19.  
  20. desc
  21. @@
  22.  
  23.  
  24. 1.2
  25. log
  26. @Unix version 5.9
  27. @
  28. text
  29. @.\" Copyright (c) 1988 The Regents of the University of California.
  30. .\" All rights reserved.
  31. .\"
  32. .\" Redistribution and use in source and binary forms are permitted
  33. .\" provided that the above copyright notice and this paragraph are
  34. .\" duplicated in all such forms and that any documentation,
  35. .\" advertising materials, and other materials related to such
  36. .\" distribution and use acknowledge that the software was developed
  37. .\" by the University of California, Berkeley.  The name of the
  38. .\" University may not be used to endorse or promote products derived
  39. .\" from this software without specific prior written permission.
  40. .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  41. .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  42. .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  43. .\"
  44. .\"    @@(#)getpwent.3    6.5 (Berkeley) 2/23/89
  45. .\"
  46. .TH GETPWENT 3  "February 23, 1989"
  47. .AT 3
  48. .SH NAME
  49. getpwent, getpwnam, getpwuid, setpassent,
  50. setpwfile, setpwent, endpwent \- get password file entries
  51. .SH SYNOPSIS
  52. .nf
  53. .B #include <sys/types.h>
  54. .B #include <pwd.h>
  55. .PP
  56. .B struct passwd *getpwent()
  57. .PP
  58. .B struct passwd *getpwnam(login)
  59. .B char *login;
  60. .PP
  61. .B struct passwd *getpwuid(uid)
  62. .B uid_t uid;
  63. .PP
  64. .B int setpassent(stayopen)
  65. .B int stayopen;
  66. .PP
  67. .B void setpwfile(file)
  68. .B char *file;
  69. .PP
  70. .B int setpwent()
  71. .PP
  72. .B void endpwent()
  73. .fi
  74. .SH DESCRIPTION
  75. .IR Getpwent ,
  76. .IR getpwuid ,
  77. and
  78. .I getpwnam
  79. each return a pointer to a structure containing the broken-out
  80. fields of a line in the password file.  This structure is defined
  81. by the include file
  82. .IR < pwd.h > ,
  83. and contains the following fields:
  84. .PP
  85. .RS
  86. .nf
  87. struct passwd {
  88.     char    *pw_name;            /* user name */
  89.     char    *pw_passwd;        /* encrypted password */
  90.     uid_t    pw_uid;        /* user uid */
  91.     gid_t    pw_gid;        /* user gid */
  92.     time_t    pw_change;    /* password change time */
  93.     char    *pw_class;        /* user access class */
  94.     char    *pw_gecos;        /* Honeywell login info */
  95.     char    *pw_dir;            /* home directory */
  96.     char    *pw_shell;        /* default shell */
  97.     time_t    pw_expire;    /* account expiration */
  98. };
  99. .fi
  100. .RE
  101. .PP
  102. These fields are more completely described in
  103. .IR passwd (5).
  104. .PP
  105. .I Getpwnam
  106. and
  107. .I getpwuid
  108. search the password database for a matching user name or user uid,
  109. respectively, returning the first one encountered.  Identical
  110. user names or user uids may result in undefined behavior.
  111. .PP
  112. .I Getpwent
  113. sequentially reads the password database and is intended for programs
  114. that wish to step through the complete list of users.
  115. .PP
  116. All three routines will open the password file for reading, if
  117. necessary.
  118. .PP
  119. .I Setpwfile
  120. changes the default password file to
  121. .IR file ,
  122. thus allowing the use of alternate password files.
  123. .PP
  124. .I Setpassent
  125. opens the file or rewinds it if it is already open.  If
  126. .I stayopen
  127. is non-zero, file descriptors are left open, significantly speeding
  128. up subsequent calls.  This functionality is unnecessary for
  129. .I getpwent
  130. as it doesn't close its file descriptors by default.  It should also
  131. be noted that it is dangerous for long-running programs to use this
  132. functionality as the password file may be updated by
  133. .IR chpass (1),
  134. .IR passwd (1),
  135. or
  136. .IR vipw (8).
  137. .PP
  138. .I Setpwent
  139. is identical to
  140. .I setpassent
  141. with an argument of zero.
  142. .PP
  143. .I Endpwent
  144. closes any open files.
  145. .PP
  146. These routines have been written to ``shadow'' the password file, e.g.
  147. allow only certain programs to have access to the encrypted password.
  148. This is done by using the
  149. .IR mkpasswd (8)
  150. program, which creates
  151. .IR ndbm (3)
  152. databases that correspond to the password file, with the single exception
  153. that, rather than storing the encrypted password in the database, it stores
  154. the offset in the password file where the encrypted password may be found.
  155. .IR Getpwent ,
  156. .IR getpwnam ,
  157. and
  158. .I getpwuid
  159. will use the
  160. .I ndbm
  161. files in preference to the ``real'' password files, only reading the
  162. password file itself, to obtain the encrypted password, if the process
  163. is running with an effective user id equivalent to super-user.
  164. If the password file itself is protected, and the
  165. .I ndbm
  166. files are not, this makes the password available only to programs
  167. running with super-user privileges.
  168. .SH FILES
  169. /etc/passwd
  170. .SH "SEE ALSO"
  171. getlogin(3), getgrent(3), ndbm(3), passwd(5)
  172. .SH DIAGNOSTICS
  173. The routines
  174. .IR getpwent ,
  175. .IR getpwnam ,
  176. and
  177. .IR getpwuid ,
  178. return a null pointer on EOF or error.
  179. .I Setpassent
  180. and
  181. .I setpwent
  182. return 0 on failure and 1 on success.
  183. .I Endpwent
  184. and
  185. .I setpwfile
  186. have no return value.
  187. .SH BUGS
  188. All information is contained in a static buffer which is overwritten
  189. by each new call.  It must be copied elsewhere to be retained.
  190. .PP
  191. Intermixing calls to
  192. .IR getpwent
  193. with calls to
  194. .I getpwnam
  195. or
  196. .IR getpwuid ,
  197. or intermixing calls to
  198. .I getpwnam
  199. and
  200. .IR getpwuid ,
  201. after using
  202. .I setpassent
  203. to require that file descriptors be left open, may result
  204. in undefined behavior.
  205. .PP
  206. The routines
  207. .IR getpwent ,
  208. .IR endpwent ,
  209. .IR setpassent ,
  210. and
  211. .IR setpwent
  212. are fairly useless in a networked environment and should be
  213. avoided, if possible.
  214. @
  215.  
  216.  
  217. 1.1
  218. log
  219. @Initial revision
  220. @
  221. text
  222. @d1 2
  223. a2 1
  224. .\"    @@(#)getpwent.3    6.3 (Berkeley) 5/15/86
  225. d4 15
  226. a18 1
  227. .TH GETPWENT 3  "May 15, 1986"
  228. d21 2
  229. a22 1
  230. getpwent, getpwuid, getpwnam, setpwent, endpwent, setpwfile \- get password file entry
  231. d25 1
  232. d28 5
  233. d34 1
  234. a34 4
  235. .B int uid;
  236. .PP
  237. .B struct passwd *getpwnam(name)
  238. .B char *name;
  239. d36 2
  240. a37 1
  241. .B struct passwd *getpwent()
  242. d39 2
  243. a40 1
  244. .B setpwent()
  245. d42 1
  246. a42 1
  247. .B endpwent()
  248. d44 1
  249. a44 2
  250. .B setpwfile(name)
  251. .B char *name;
  252. d47 2
  253. a48 2
  254. .I Getpwent,
  255. .I getpwuid
  256. d51 6
  257. a56 4
  258. each return a pointer to an object with the
  259. following structure
  260. containing the broken-out
  261. fields of a line in the password file.
  262. a57 1
  263. .PP
  264. d59 12
  265. a70 3
  266. .so /usr/include/pwd.h
  267. .ft R
  268. .ad
  269. d74 1
  270. a74 5
  271. The fields
  272. .I pw_quota
  273. and
  274. .I pw_comment
  275. are unused; the others have meanings described in
  276. d77 1
  277. a77 7
  278. Searching of the password file is done using the \fIndbm\fP
  279. database access routines.
  280. .I Setpwent
  281. opens the database;
  282. .I endpwent
  283. closes it.
  284. .I Getpwuid
  285. d79 8
  286. a86 6
  287. .I getpwnam
  288. search the database (opening it if necessary) for a matching
  289. .I uid
  290. or
  291. .IR name .
  292. EOF is returned if there is no entry.
  293. d88 2
  294. a89 9
  295. For programs wishing to read the entire database,
  296. .I getpwent
  297. reads the next
  298. line (opening the database if necessary).
  299. In addition to opening the database,
  300. .I setpwent
  301. can be used to make
  302. .I getpwent
  303. begin its search from the beginning of the database.
  304. d93 47
  305. a139 8
  306. .I name
  307. thus allowing alternate password files to be used.
  308. Note that it does
  309. .I not
  310. close the previous file.
  311. If this is desired,
  312. .I endpwent
  313. should be called prior to it.
  314. d143 1
  315. a143 1
  316. getlogin(3), getgrent(3), passwd(5)
  317. d147 2
  318. d150 6
  319. d157 2
  320. a158 2
  321. .IR getpwnam ,
  322. return a null pointer (0) on EOF or error.
  323. d160 26
  324. a185 4
  325. All information
  326. is contained in a static area
  327. so it must be copied if it is
  328. to be saved.
  329. @
  330.